home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d1 / freemacs.arc / EMACS.DOC < prev    next >
Encoding:
Text File  |  1988-03-17  |  12.6 KB  |  307 lines
  1.         The Freemacs extension writer's guide to MINT functions.
  2.  
  3. Introduction:
  4.  
  5.     This document purports to explain how an ordinary person may be
  6. transformed into a Freemacs wizard.  In doing so, only those functions
  7. that are called by a wizard will be explained.  Function that are called
  8. only by other functions and functions bound to keys will not be explained
  9. There is no prohibition against calling them yourself, but they are not
  10. documented.
  11.  
  12.  
  13. Assumptions:
  14.  
  15.     You are assumed to be familiar with the operation of the Freemacs
  16. editor.  You are also assumed to have read the tutorial (TUTORIAL.DOC)
  17. and reference (REFERENCE.DOC) documents for the MINT language.
  18.  
  19. Notation:
  20.  
  21.     When a specific function is referred to, it will be expressed as
  22. a MINT active default function.  Arguments to the function will be given
  23. only if they are  referred to.  When a MINT string that is not a function
  24. is referred  to, it will be expressed as a neutral default function.  A
  25. string of capital letters means what it says, which is either obvious
  26. from the context, or explained in the surrounding text.  Other strings
  27. will be set off by double quotes.
  28.     Examples:
  29.  
  30.     #(Fbuffer-fn) refers to the function "buffer-fn" in library F.
  31.     ##(lib-list) refers to the contents of the string "lib-list".
  32.     ##(filename.BUFFER NUMBER) refers to the contents of the string
  33.       having the name "filename." concatenated with a buffer number.
  34.  
  35.  
  36. Counts:
  37.  
  38.     Every function whose name is #(X:x-x-x), that is to say, every
  39. function whose second character is ':' is executable by the user.  Each
  40. function may be passed one argument or not.  If the function knows how to
  41. deal with an argument, then the function begins with a TAB.  Functions
  42. that don't know how to deal with an argument may safely be repeated using
  43. #(Floop).
  44.  
  45.  
  46. Filenames:
  47.  
  48.     Each buffer has a filename associated with it.  This filename is
  49. held in #(buffer fn.BUFFER) where BUFFER is the buffer number.
  50. ##(Fdefault ext) contains the extension used whenever a filename doesn't
  51. specify an extension.
  52.  
  53.  
  54. Libraries:
  55.  
  56.     A library is a disk file that contains MINT strings stored in a
  57. special form.  Strings whose name begins in a capital letter, called the
  58. library letter, belong to a library.  The filename of the library is held in
  59. ##(LIBRARY LETTERfilename).  A library stored on disk contains
  60. only strings whose names begin with the library letter and ##(lib name),
  61. a string that contains just the library letter.  This is done so that the
  62. library letter of a just loaded library may be easily determined.  A list
  63. of the library letters of all loaded libraries is in ##(lib list).  The last
  64. library loaded is the first letter in ##(lib list).
  65.     A library is loaded with #(Fload lib,FILENAME).  A library is
  66. saved with #(Fsave lib,FILENAME).  All the libraries may be saved in their
  67. respective files using #(Fsave all).  After a library is loaded #(LIBRARY
  68. LETTER&setup) is executed, which performs whatever initialization is
  69. required by the library.
  70.     If the string ##(LIB LETTERmodified) exists, then the library has
  71. been modified and should be saved to disk.  #(F:save-all-libs) will save
  72. any libs that have been modified.
  73.  
  74.  
  75. Buffers:
  76.  
  77.     Freemacs initially fires up with only one buffer, numbered one
  78. However, Freemacs needs a buffer for its own use, the edit buffer, so it
  79. creates another buffer which is numbered two.  Rather than confuse the
  80. user by starting with buffer two, the users buffer numbers start with one.
  81.     ##(buffer-mode.BUFFER NUMBER) contains the mode of the buffer.
  82. ##(buffer-type.BUFFER NUMBER) contains the type of the buffer (eg.  FILE,
  83. EDIT, SCR , MAKE, etc).  This type should always be four characters long.
  84. ##(buffer-filename.BUFFER NUMBER) contains the filename of the buffer.  If
  85. the buffer has no filename then the string will not exist.
  86.     #(Ffor-all-buffers,STRING) will execute the function named in
  87. STRING for every user buffer.  Equivalent to #(ba,2)STRING #(ba,3)STRING,
  88. etc. for all the buffers that exist.  #(Fbuffer-modified,YES,NO) executes
  89. YES if the buffer has been modified, otherwise it executes NO.  #(Fsave
  90. buffer if modified) will save the buffer into ##(buffer-filename).tmp if
  91. the buffer has been modified.  #(Fok-to-trash-buffer,FUNCTIONS) asks the
  92. user if it is ok to trash the buffer.  If the user responds with 'y',
  93. then FUNCTIONS is executed.
  94.  
  95. #(Fuse-edit-buffer) will switch to the edit buffer.  You may insert
  96. anything into the edit buffer that doesn't cause problems with #(Mstring-read)
  97. #(Ftrash-buffer) gives the user a chance to save unsaved changes.
  98.  
  99.  
  100. Editing a string:
  101.  
  102.     A string may be edited using #(M:ef,STRING).  This causes an EDIT
  103. buffer (See "Buffers") to be selected and the string brought into the
  104. buffer for editing.  #(M:ef,STRING) actually selects all strings whose
  105. name starts with STRING.  This is a useful property since related
  106. functions share a common prefix on their names.  Additional strings may
  107. be edited by using #(M:ef,STRING) again.  #(M:give-name,STRING) enters a
  108. null definition for STRING.
  109.     Once the string is in the edit buffer, it may be edited like
  110. ordinary text.  When you are satisfied with the changes, you may execute
  111. #(M:done-editing).  This causes the strings to be redefined with the new
  112. contents.  If you are not satisfied with the changes and wish to throw
  113. them away, simply delete the entire string, name and all.
  114.     If the string ##(LIB LETTERmodified) exists, then the library has
  115. been modified and should be saved to disk.  #(F:save-all-libs) will save
  116. any libs that have been modified.
  117.  
  118.  
  119.  
  120. Initialization:
  121.  
  122.     #(F&setup) is the first function executed after loading the
  123. library "emacs.ed".  #(lib list) is initialized to contain only "F", the
  124. rest of the MS-DOS command line is processed, and three special strings
  125. are defined.  These two strings are #(d), #(g), and #(k).  These strings
  126. are executed by the idling string (See "The Freemacs Reference Manual").
  127. #(d) has one argument, the name of a key, which it then processes.  #(g)
  128. waits for a key to be input and returns its value.  #(k) redisplays the
  129. screen and updates the mode line.
  130.  
  131. This is the function executed when emacs first starts up:
  132.  
  133. #(rd)#(ow,(
  134. EMACS, a programmable editor - Version 1.03
  135. Copyright (C) Russell Nelson 1986, 1987
  136. ))
  137. #(ev)
  138. #(an,Loading #(env.EMACS)emacs.ed...)
  139. #(==,#(ll,#(env.EMACS)emacs.ed#(es,#(ls,(,)))),,(
  140.     #(an,Starting editor...)
  141.     #(##(lib-name)&setup)
  142. ),(
  143.     #(ow,Cannot find 
  144.         #(ev)
  145.         #(env.EMACS)emacs.ed - halting)
  146.     #(hl,1)
  147. ))
  148.  
  149.  
  150. Key bindings:
  151.  
  152.     There is a special library for key bindings, K (filename keys.ed).
  153. This is done so that a user can develop their own key bindings without
  154. changing the 'emacs' library.  Keyboard macros saved with
  155. #(F:name-kbd-macro,NAME) get placed into the K library.
  156.     When a key is pressed, the function associated with that key is
  157. executed.  If there is no function associated with that key,
  158. #(Fself-insert) is executed.  A function is associated with a key if
  159. #(K.KEY) exists.  #(F:bind-to-key,FUNC,KEY) will assign FUNC to KEY, and
  160. will prompt if either is missing.  This is done by defining a string
  161. #(K.KEY) to be "FUNC".  #(F:unbind-key) will prompt for a key and delete
  162. #(K.KEY).
  163.     The function #(M:keys-edit) will create an EDIT buffer (See
  164. "buffers") and insert all the key bindings into it.  The function
  165. #(M:keys-read) will read them out again.
  166.  
  167.  
  168. Marks:
  169.  
  170.     A ring of global marks is kept.  This is done by allocating
  171. sixteen global marks @ through F, and running through them one at a time
  172. The current mark is ##(Fmark).  Whenever a function moves point  off of
  173. the screen, a new global mark is set.  #(Fset-new-mark,MARK) will
  174. increment ##(Fmark), wrapping F around to @, and set the new mark to
  175. MARK.  #(Fexchange-point-and-mark) will do just that.
  176.  
  177.  
  178. Regions:
  179.  
  180.     All the text between the point and the current mark (See Marks)
  181. is considered a region.  #(Fregion-chars,FUNC) will process the region
  182. character by character by applying the function and insert the results
  183. again.  The function maps a decimal representation of a character into a
  184. decimal representation of a character.  #(F:lowercase-region) is an
  185. example of this type of function.
  186.  
  187.  
  188. User input:
  189.  
  190.     Functions need to prompt for and accept input from the user.
  191. #(Freadline,PROMPT,ACTION,HELP,MODE) does just that.  The user is
  192. prompted with the string PROMPT.  The user types a string (typically) and
  193. hits return, at which time ACTION is executed with ##(value) equal to the
  194. string that the user input.  ACTION usually consists of a number of MINT
  195. functions.  The user is given an initial value that he may accept or
  196. reject in ##(value).  Any key other than return rejects the initial value.
  197.     #(Freadline) causes the user to enter into a temporary mode, in
  198. which his keystrokes are interpreted differently.  If #(MODE.KEY) exists,
  199. it is executed else if #(Freadline.KEY) exists, it is executed, otherwise
  200. #(Freadline.other) is executed.
  201.  
  202. #(Fextended-command.C-[) completes a string name
  203. #(Fextended-command.?) lists string names that match the current string.
  204.  
  205. #(Freadline.C-H) deletes a character.
  206. #(Freadline.Delete) deletes a character.
  207. #(Freadline.other) processes all undefined characters.
  208. #(Freadline.C-L) brings in the character following point.
  209. #(Freadline.C-O) brings in the word following point.
  210. #(Freadline.C-U) aborts the input.
  211. #(Freadline.C-C) aborts the input.
  212. #(Freadline.C-M) accepts the input and executes ACTION.
  213.  
  214.  
  215. Looping:
  216.  
  217.     #(Floop,VALUE,COUNT) will rescan VALUE COUNT times.
  218.  
  219.  
  220.  
  221. Rings:
  222.  
  223.     Freemacs provided a facility for keeping a fixed size ring of
  224. strings.  At any one time one of the strings is considered to be at the
  225. head of the ring.  This string may be accessed using #(Fhead,RING) where
  226. RING is the name of the ring.  The size of the ring is kept in ##(FRING.size).
  227. The name of the string that is at the head of the string is ##(FRING.head).
  228. The ring may be rotated using #(Frotate,RING), and unrotated using
  229. #(Funrotate,RING).  The head of the ring may be modified by setting
  230. ##(value) to the desired value and executing #(Freplace head,RING).
  231. #(Fring,RING,SIZE) initializes a new ring.
  232.  
  233.  
  234. Killing:
  235.  
  236.     Freemacs provides a kill ring (See Rings) which keeps the last eight
  237. items killed.  The head of the ring may be inserted using #(Fun-kill).
  238. #(Fkill,MARK) may be used to kill from the point to MARK.  If ##(result)
  239. is "kill", the killed text is appended to the previous kill, otherwise
  240. the kill ring is rotated and a new kill is created.  #(F:append next kill)
  241. simply sets ##(result) to "kill" so that the next kill is appended.
  242. #(Fbackward kill,MARK) is used to kill a string from MARK to the point.
  243. This preserves the order of killed text.
  244.     Rather than store the killed strings in the MINT string space,
  245. they are stored in buffer one, which is reserved by Freemacs for the kill
  246. buffer.  Marks @ through H are set on vertical bar characters ("|").  The
  247. eight strings are stored between the vertical bars.
  248.  
  249.  
  250.  
  251. Stacks:
  252.  
  253.     Any string may be turned into a stack using #(Fredefine,STRING,VAL).
  254. VAL must have balanced parentheses.  When the default or #(gs) built-in
  255. function is executed, the string seems to contain just VAL.  The previous
  256. contents may be restored using #(Funredefine,STRING).
  257.     One use of this may be seen in #(Fhit any key).
  258.  
  259.  
  260. Misc:
  261.  
  262. #(Fmax,A,B) returns the numerically greater of A and B.
  263.  
  264. #(Ftoupper,CHAR) maps ASCII values into ASCII values.  Only lower case
  265. letters are changed to upper case.
  266.  
  267. #(Ftolower,CHAR) maps ASCII values into ASCII values.  Only upper case
  268. letters are changed to lower case.
  269.  
  270. #(Fisupper,CHAR,YES,NO) tests the ASCII value of char and executes YES
  271. if the character is an upper case letter or NO if not.
  272.  
  273. #(Fpad-to-column,COL) will append enough tabs and spaces to the line to
  274. put the point at the given column.
  275.  
  276. #(Fyes-or-no,,YES,NO) will wait for a key and execute YES if
  277. that key is 'Y', or 'y'.  It will execute NO if the key is 'N' or 'n'.
  278. It keeps trying until a recognized key is hit.
  279.  
  280. #(Ferror,ERROR) will report ERROR as an error only if it is non-null.
  281.  
  282. ##(F-fill-column) is the column used by #(Fformat paragraph)
  283.  
  284. ##(F-comment-column) is the column that comments should be aligned to.
  285.  
  286. #(Fmultiple,STRING,LIST) will execute #(STRING,LIST ELEMENT) where LIST
  287. consists of LIST ELEMENTS seperated by commas.  Note that LIST can not be
  288. scanned, otherwise the commas will be converted to argument seperators.  Use
  289. parentheses to protect LIST, or use a neutral function to return its results
  290. unscanned.
  291.  
  292. #(Fcase,arg1,
  293.     (new,(
  294.         stuff to scan if arg1 = new.
  295.     )),
  296.     (forward,(
  297.         stuff to scan if arg1 = forward.
  298.     )),
  299.     (backward,(
  300.         stuff to scan if arg1 = backward.
  301.     )),
  302.     (else,(
  303.         stuff to scan if arg1 isn't any of the above
  304.     ))
  305. )
  306.  
  307.